Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

NSCursor

Inherits From:	NSObject

Conforms To:	NSCoding
NSObject (NSObject)

Inherits From:	AppKit/NSCursor.h

Class Description

An NSCursor holds an image that the window system can display for the cursor. An NSCursor is initialized with an NSImage object (which can subsequently be replaced by sending the NSCursor a setImage: message). To make the window system display a particular image as the current cursor, simply send a set message to the NSCursor instance associated with that image. 

For automatic cursor management, an NSCursor can be assigned to a cursor rectangle within a window. When the window is key and the user moves the cursor into the rectangle, the NSCursor becomes the current cursor. It ceases to be the current cursor when the cursor leaves the rectangle. The assignment is made using NSView's addCursorRect:cursor: method, usually inside a resetCursorRects method:

- (void)resetCursorRects
{
    [self addCursorRect:someRect cursor:theNSCursorObject];
}

This is the recommended way of associating a cursor with a particular region inside a window. However, the NSCursor class provides two other ways of setting the cursor:

·	The class maintains its own stack of cursors. Pushing an NSCursor instance on the stack sets it to be the current cursor. Popping an NSCursor from the stack sets the next NSCursor in line, the one that's then at the top of the stack, to be the current cursor.

·	An NSCursor can be made the owner of a tracking rectangle and told to set itself when it receives a mouse-entered or mouse-exited event.

The Application Kit provides two ready-made NSCursor instances: the standard arrow cursor, and the I-beam cursor that's displayed over editable or selectable text. These can be retrieved with the class methods arrowCursor and IBeamCursor, respectively. There's no NSCursor instance for the wait cursor. The wait cursor is displayed automatically by the system, without any required program intervention.

Initializing a New NSCursor Object

- (id)initWithImage:(NSImage *)newImage	Initializes a new NSCursor object with newImage.

Defining the Cursor

- (NSPoint)hotSpot	Returns the point on the cursor that's aligned with the mouse.

- (NSImage *)image	Returns the NSImage object that has the cursor image.

- (void)setHotSpot:(NSPoint)spot	Sets the point on the cursor that's aligned with the mouse.

- (void)setImage:(NSImage *)newImage	Makes newImage the NSImage object that supplies the cursor image.

Setting the Cursor

+ (void)hide	Hides the cursor. 

+ (void)pop	Restores the previous cursor.

+ (void)setHiddenUntilMouseMoves:(BOOL)flag;	Hides cursor when flag is YES; reveals it otherwise.

+ (void)unhide	Shows the cursor.

- (BOOL)isSetOnMouseEntered	Returns YES if mouseEntered: sets cursor.

- (BOOL)isSetOnMouseExited	Returns YES if mouseExited: sets cursor.

- (void)mouseEntered:(NSEvent *)theEvent	Responds to a mouse-entered event by setting the cursor if setOnMouseEntered was sent.

- (void)mouseExited:(NSEvent *)theEvent	Responds to a mouse-exited event by setting the cursor if setOnMouseExited was sent.

- (void)pop	Removes the topmost NSCursor object from the cursor stack, and makes the next NSCursor down the current cursor.

- (void)push	Puts the receiving NSCursor on the cursor stack and sets it to be the current cursor. 

- (void)set	Sets the NSCursor to be the current cursor.

- (void)setOnMouseEntered:(BOOL)flag	Determines whether mouseEntered: sets cursor.

- (void)setOnMouseExited:(BOOL)flag	Determines whether mouseExited: sets cursor.

Getting the Cursor

+ (NSCursor *)arrowCursor	Returns an arrow cursor. 

+ (NSCursor *)currentCursor	Returns the current cursor.

+ (NSCursor *)IBeamCursor	Returns an I-beam cursor.